home *** CD-ROM | disk | FTP | other *** search
/ Collection of Tools & Utilities / Collection of Tools and Utilities.iso / c / ansippv2.zip / READ.ME < prev    next >
Text File  |  1988-09-21  |  23KB  |  460 lines
  1.  
  2. Thanks for your gratifying response to my article in Computer Language, July
  3. 1988, titled "Using Tomorrow's C Standard Today".  This disk contains the
  4. latest source and executable code for the ANSI-Conforming C Language
  5. Preprocessor presented there.  This is contained in the archive PPV2.ARC.
  6.  
  7.                              Don Kneller's NDMAKE
  8.  
  9. Also included is Don Kneller's NDMAKE utility, which is used to maintain the
  10. preprocessor.  If you didn't have a MAKE utility before, you now have one of
  11. the best.  If you decide to use it, be sure to support Don's efforts by
  12. becoming a legal user of NDMAKE.  This is contained in the archive
  13. NDMAKE43.ARC.
  14.  
  15. I have included NDMAKE at no charge.  Any charge for this disk is for the
  16. preprocessor, not NDMAKE.
  17.  
  18. Don also markets a commercial version with even more features, called OPUS
  19. Make.  It is available from:
  20.  
  21.         OPUS Software
  22.         D.G. Kneller and J.F. Thomason
  23.         1032 Irving Street
  24.         Suite 439
  25.         San Francisco, CA 94122
  26.  
  27.                                Phil Katz's PKPAK
  28.  
  29. Both archives may be unpacked using Phil Katz's unsurpassed PKPAK (formerly
  30. PKARC) utility, which is contained in the self-extracting archive PK361.EXE.
  31. Simply running PK361.EXE will unpack Phil's program and documentation into
  32. the current directory.  Again, if you find PKPAK useful, please register with
  33. Phil as a legal user.
  34.  
  35. (Phil and his company PKWARE have recently been the target of a lawsuit by
  36. SEA, with whose ARC.EXE program PKPAK is compatible.  You may read the text of
  37. their settlement and decide for yourself, but many people think that Phil was
  38. treated unfairly.  By providing us with a fast and useful tool, he exposed
  39. himself to this kind of action, and so we all owe him a great deal.)
  40.  
  41. I have included PKPAK at no charge.  Any charge for this disk is for the
  42. preprocessor, not PKPAK.
  43.  
  44.                             Revision Control System
  45.  
  46. I hope that you will learn from examining this source code.  I also hope that
  47. you will make changes to it, so that it better suits your needs.  If you do,
  48. you will probably find a revision control system as useful as I do.  One of
  49. the most affordable, as well as fast and capable, is TLIB, available from:
  50.  
  51.         Burton Systems Software
  52.         P.O. Box 4156
  53.         Cary, NC 27519-0156
  54.         (919) 469-3068
  55.  
  56. TLIB allows you to keep track of your revisions as you make them, and also to
  57. merge my changes into your own if I send you a new version.  Once you start
  58. using a revision control system, you just can't stop.
  59.  
  60.                                 The ANSI Draft
  61.  
  62. Anyone who seriously wants to use the preprocessor should obtain a copy of the
  63. ANSI draft from the address in PP.MAN.  Unfortunately, its expensive, but
  64. there's no other way to learn the new features and behavior.
  65.  
  66. The comments in this source code often refer to sections in the ANSI draft.
  67. Those comments, and the entire preprocessor, are based on the draft dated
  68. January 11, 1988, which is already outdated.  If you obtain the ANSI draft
  69. today, you will receive a later revision.  The section numbers should be
  70. close.  Whether the behavior is close depends on the changes they have made.
  71.  
  72.                                The Preprocessor
  73.  
  74. The following files are included in PPV2.ARC:
  75.  
  76.         ANSI.DAT        ANSI "Torture test" examples
  77.         ASSERT.H        An ANSI assert() macro
  78.         ERROR.C         Error message function.
  79.         ERROR.H         Error message function.
  80.         MAKE.INI        Use with Don Kneller's NDMAKE
  81.         MAKEFILE        Use with Don Kneller's NDMAKE
  82.         MEMORY.C        Memory allocation functions.
  83.         MEMORY.H        Memory allocation functions.
  84.         PP.C            Standalone preprocessor.
  85.         PP.EXE          Standalone preprocessor.
  86.         PP.H            Definitions for PP.LIB.
  87.         PP.MAN          Brief description of usage
  88.         PPCHAR.C        Handle trigraph translation.
  89.         PPDIRECT.C      Preprocessor directives.
  90.         PPIFS.C         #if and related directives.
  91.         PPMACRO.C       #define #undef Macro replacement
  92.         PPTOK.C         Tokenizer.
  93.         SYMTAB.C        Hashed symbol table functions.
  94.         SYMTAB.H        Hashed symbol table functions.
  95.         VERS2.H         A little file used by ANSI.DAT.
  96.  
  97.                           Differences From Version 1
  98.  
  99. The following are a list of differences between Version 1 and Version 2 of the
  100. preprocessor.  Any user who has made changes to the Version 1 source code may
  101. contact me to receive a full TLIB revision history of my changes.  This would
  102. allow that user to use TLIB to merge my changes with his or her own.
  103.  
  104. The preprocessor now runs about twice as fast, due to compilation with the
  105. Watcom C Compiler.
  106.  
  107. The source code itself is closer to ANSI-Conformance, although it still fails
  108. to conform in many places.  The primary change is to use prototype function
  109. declarations.  Note that the this comment applies to the source code itself,
  110. not to the function of the program.  It has always been intended that the
  111. program functions as an ANSI-Conforming C Language Preprocessor.  It is
  112. possible for non-conforming C source code to fit that function.
  113.  
  114. A bug was corrected that produced an incorrect macro replacement or a
  115. diagnostic when any macro invocation contained a parameter that began with a
  116. left parenthesis.  For example, the input:
  117.  
  118.         #define str(x) / #x /
  119.         #define cat(x, y) | #x #y |
  120.  
  121.         These work OK:
  122.  
  123.         str(test)
  124.         cat(left, right)
  125.  
  126.         These work not OK:
  127.  
  128.         str((test))
  129.         cat((left), (right))
  130.  
  131. produces the following output:
  132.  
  133.         These work OK:
  134.  
  135.         / "test" /
  136.         | "leftright" |
  137.  
  138.         These work not OK:
  139.  
  140.         / "(test" /)
  141.         12: Too few macro arguments.
  142.         , (right))
  143.  
  144. A bug was corrected that produced garbage upon certain invalid #include
  145. directives.
  146.  
  147. #pragma directives are now optionally passed through to the output.  Within
  148. passed-through #pragma directives, macros may be replaced, optionally.  If
  149. #pragma pass-through is disabled (as by default), #pragma directives are
  150. silently ignored and discarded.  This change allows the preprocessor to work
  151. correctly with compilers such as Watcom, to whom #pragma directives are
  152. important.  It also allows the preprocessor to correctly handle input that
  153. contains #pragma directives; previously, only the simplest #pragma directives
  154. were discarded without complaint.
  155.  
  156. The preprocessor now scrupulously frees all dynamically allocated memory.
  157. Previously, memory allocated for the symbol table, and certain other data, was
  158. never freed, because it is used throughout the execution of the preprocessor.
  159. This change is only for my peace of mind.  It may be more significant to
  160. others that write programs that call the preprocessor library: a new function,
  161. PPTerminate(), ensures that all memory allocated by the library is freed.
  162.  
  163. Dynamic memory allocation is now performed via malloc() and free().
  164. Previously, the preprocessor library chose between malloc() and sbrk()
  165. depending on the size of the memory to be allocated.  This was important under
  166. the Lattice compiler, whose malloc() and free() are excruciating.  There is no
  167. apparent advantage under Watcom, and sbrk() caused other problems.
  168.  
  169. The NDEBUG macro in ASSERT.H worked backwards.  That is, defining NDEBUG
  170. enabled the assert() macro, instead of disabling it as it should.
  171.  
  172. The __DATE__ and __TIME__ predefined macros are now replaced with the current
  173. date and time, instead of a canned date and time.
  174.  
  175. Other minor changes to the source code and comments.
  176.  
  177.                                  The Compiler
  178.  
  179. This version may be compiled using the Watcom C Compiler version 6.5.  I have
  180. also compiled it with various versions of Microsoft C, and it works.  More on
  181. the Watcom compiler below.
  182.  
  183. If you don't use the Watcom compiler, you can probably use your favorite
  184. compiler instead without too much trouble, provided your compiler can handle
  185. prototype function declarations.  (This elim